<html>

	<head>
		<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
		<meta name="generator" content="Adobe GoLive 5">
		<title>Tutorial 4. Running multiple JADE platforms</title>
		<link rel="stylesheet" href="../cps.css">
	</head>

	<body bgcolor="#d3d3d3" text="black">
	
		<a href="index.html">Table of contents</a><br>
		<a href="jadeContainerTutorial.html">Previous</a><br>
		<hr>
		
		<h1>Tutorial 4. Running multiple JADE platforms</h1>
		<p>In Tutorial 2 and 3 we saw a single JADE platform consisting of one Main Container and a number
		of peripheral containers running locally as well as on remote computers. We also mentioned that agents 
		living in the same platform (no matter if they are in the same or in different containers) communicate 
		by sending messages and indicating the name of the receiver(s) is sufficient for a message to be delivered
		correctly. In this tutorial we will show how
		to start multiple JADE platforms and we will make agents belonging to different platforms communicate.
		As we will describe later in this section, for this to work properly it is necessary that the AID of the
		receiver of a message includes, beside the receiver's name, at least one transport address of the 
		receiver's platform.</p>
		
		<h2>MTP</h2>
		<p>Inter-platform communication, i.e. communication between agents living on different platforms, is
		based on modules called MTP (Message Transport Protocol). Such modules are able to marshal/un-marshal and  
		transmit ACL messages according to the <a href="http://www.fipa.org">FIPA</a> specifications. In this way JADE
		agents are able to communicate with agents living on remote platforms regardless of whether these are
		other JADE platforms or different platforms (possibly developed with a different programming language) 
		provided that they are FIPA compliant. FIPA specifies how to transfer ACL messages over three well known
		transport protocols: HTTP, IIOP (the transport protocol defined in CORBA) and SMTP. JADE provides
		suitable MTPs for HTTP and IIOP only.</p>
		<p>MTP modules can be installed in whatever container and a container can have zero or more MTP modules
		installed in it. By default JADE installs the HTTP MTP in a Main Container and no MTP on peripheral containers.
		Actually if you go back to the output generated by JADE when we started the Main Container in 
		<a href="startJade.html">Tutorial 2</a> we can see that an MTP listening for messages from remote 
		platforms on port <tt>7778</tt> was activated as highlighted below.<br>
		<br>
		<img src="images/jadeOutputMTPAddress.png"  border="0"><br>
		<br>
		If you look at the output of a peripheral container you will notice that no MTP was installed. This default
		behaviour can be changed by means of the <tt>-mtps &lt;MTP-class-name-list&gt;</tt> option that allows
		specifying which MTP modules to start in each container. Furthermore the <tt>-nomtp</tt> option tells 
		JADE not to start any MTP in the Main Container.</p>
		
		<p>Agents running in a Container with no MTP are able to communicate with agents in remote platform anyway since 
		JADE routes messages directed to foreign agents to the first container hosting a suitable MTP as depicted 
		Figure 1.<br> 
		<br>
		<img src="images/interPlatformCommunication.png"  border="0"><br>
		<b>Figure 1. Message routing to/from MTP modules</b>
		</p> 
		<p>The scenario depicted in Figure 1 involves 2 platforms: <tt>Platform1</tt> composed of the Main Container, 
		running in <tt>host2</tt> and hosting an HTTP MTP, and a peripheral container called <tt>Container-1</tt> 
		running in <tt>host1</tt> and holding agent <tt>A</tt>.
		<tt>Platform2</tt> on its turn is composed of the Main Container, running in <tt>host4</tt> and holding agent
		<tt>B</tt> and a peripheral container (<tt>Container-1</tt>), running in <tt>host3</tt> and hosting an 
		HTTP MTP. Note that there is no conflict between the names of the two peripheral containers (both called
		<tt>Container-1</tt>) since they belong to different platforms.<br>
		When agent <tt>A</tt> sends a message to agent <tt>B</tt> it specifies both the name of the receiver 
		<tt>B@Platform2</tt> and, since B lives in a different platform, the transport address to deliver the message 
		to B's platform. When the JADE message transport system manages such message it first look at the receiver's 
		name (<tt>B@<b>Platform2</b></tt>) and detects that it lives in a remote platform. Then it gets the address
		(<tt><b>http</b>://host3:7778/acc</tt>) and sees that an HTTP MTP is needed. As a consequence it routes the
		message to the first container hosting an HTTP MTP (the Main Container in the depicted scenario). The MTP
		will deliver the message to the remote end-point according to the FIPA specifications. The HTTP MTP in 
		<tt>Container-1</tt> of <tt>Platform2</tt>, receiving the message, looks at the receiver's name and delivers the 
		message to the Main Container where <tt>B</tt> actually lives. <b>All these steps are fully managed by JADE.
		User do not need to care about them in anyway</b>. 
		</p>
		
		<h2>Starting 2 platforms</h2>
		<p>Let's assume we have the two network-connected hosts mentioned in <a href="JadeContainerTutorial.html">Tutorial 3</a>:
		<tt>frodo</tt> and <tt>bilbo</tt> (of course you can do the same experiment on a single computer; in this
		case remember to specify different local ports for the Main Containers of the 2 platforms). 
		In order to start from a clean situation, shut down all JADE instances (if any) still running from previous 
		tutorials.<br> 
		<ol>
		<li>Launch a platform <tt>Platform1</tt> in <tt>frodo</tt> composed of
		the Main Container plus a peripheral container:
			<ul>
			<li><b>Main Container</b>: Open a shell, move to the <tt>jade</tt> directory and type<br>
			<br>
			<tt>java -cp lib\jade.jar jade.Boot -gui -platform-id Platform1</tt><br>
			<br>
			The RMA Management Console appears.<br>
			</li>
			<li><b>Peripheral Container</b>: Open another shell, move to the <tt>jade</tt> directory and type<br>
			<br>
			<tt>java -cp lib\jade.jar jade.Boot -container</tt><br>
			<br>
			</li>
			</ul>   
		</li>
		<li>Launch a platform <tt>Platform2</tt> in <tt>bilbo</tt> composed of
		the Main Container only:
			<ul>
			<li><b>Main Container</b>: Open a shell, move to the <tt>jade</tt> directory and type<br>
			<br>
			<tt>java -cp lib\jade.jar jade.Boot -gui -platform-id Platform2</tt><br>
			<br>
			The RMA Management Console appears.
			</li>
			</ul>   
		</li>
		</ol>
		</p>
		
		<h2>Inter-platform communication in practice</h2>
		<p>Now, using the RMA in <tt>Platform1</tt> (i.e. in host <tt>frodo</tt>), start a DummyAgent in container 
		<tt>Container-1</tt> of <tt>Platform1</tt> as described in <a href="startJade.html">Tutorial 2</a>. Similarly, 
		using the RMA in <tt>Platform2</tt> (i.e. in host <tt>bilbo</tt>), start a DummyAgent in the Main Container
		of <tt>Platform2</tt>. Note that both DummyAgents have the same local name <tt>da0</tt>. Again this is not 
		a problem as their actual names are different: <tt>da0@Platform1</tt> and <tt>da0@Platform2</tt>.<br> 
		Now from the <tt>Platform1</tt> DummyAgent try to send a message to the <tt>Platform2</tt> DummyAgent. In 
		<tt>Platform1</tt> DummyAgent GUI
		<ul>
		<li>Select a suitable communicative act e.g. <tt>INFORM</tt></li>
		<li>Insert some content e.g. <tt>Hello!</tt></li>
		<li>Right-click in the <tt>Receivers</tt> text field and select the <tt>Add</tt> menu item: the <tt>AID Editing</tt> 
		dialog box should appear</li>
		<li>Insert the receiver's name <tt>da0@Platform2</tt> in the <tt>NAME</tt> text field. <i><b>Do not check the 
		<tt>local name</tt> check box! This is a global name.</b></i></li>
		<li>Right-click in the <tt>Addresses</tt> text field and select the <tt>Add</tt> menu item: the <tt>Edit Address</tt>
		dialog box depicted in Figure 2 should appear.</li>
		</ul>
		<img src="images/addressEditingDialog.png"  border="0"><br>
		<b>Figure 2. The <tt>Edit Address</tt> dialog box</b>
		<ul>
		<li>Insert the receiver's address i.e. the address of <tt>Platform2</tt>. You can get it from the output of
		<tt>Platform2</tt> Main Container; it should be <tt>http://bilbo:7778/acc</tt></li>
		<li>Click <tt>OK</tt>. You should have now the <tt>AID Editing</tt> dialog box looking like that depicted in 
		Figure 3.</li>
		<li>Click <tt>OK</tt> in the <tt>AID Editing</tt> dialog box and finally click the <tt>Send Message</tt>
		button in the DummyAgent GUI.</li>
		</ul>
		<img src="images/aidEditingDialog4InterPlatformComm.png"  border="0"><br>
		<b>Figure 3. The <tt>AID Editing</tt> dialog box filled for inter-platform communication</b><br>
		</p>
		
		 
		<h2>Adding remote platforms in the RMA GUI</h2>
		<p>You will notice a menu entry in the RMA Management Console called <tt>Remote Platforms</tt>. If you click it 
		you see two ways of adding a remote platform to the JADE Management Console. <b>It is important to note that
		adding a remote platform to the RMA GUI does not affect in any way the fact that agents in the local platform
		can communicate with agents in the remote platform</b> (actually we shown this communication in the previous 
		section of this tutorial). The <tt>Add Platform</tt> operation just allows viewing the agents of the added 
		remote platform in the RMA Management GUI of the local platform.<br>
		The easiest way to add a remote platform is <tt>Add Platform via AMS AID</tt>:
		If you select this menu item you get a window which allows you to enter the AID (global name and address) of 
		the remote platform AMS. By definition (according to the FIPA specifications) the AMS of a platform is called
		<tt>ams@&lt;platform-name&gt;</tt>. So if we want to add platform <tt>Platform2</tt> to the Management Console
		of platform <tt>Platform1</tt> we should edit the <tt>AID Editing</tt> dialog box as in Figure 4.<br>
		<br>
		<img src="images/aidEditingDialog4AddPlatfromViaAMS.png"  border="0"><br>
		<b>Figure 4. The <tt>AID Editing</tt> dialog box filled for adding a platform via AMS AID</b>
		</p>
		<p>Click on the <tt>OK</tt> button and you'll see <tt>Platform2</tt> appearing in the RMA tree. Right-click
		on <tt>Platform2</tt> and select the <tt>Refresh Agent List</tt> menu item: you should get a situation similar 
		to that depicted in Figure 5.<br>
		<br>
		<img src="images/remotePlatformInRMA.png"  border="0"><br>
		<b>Figure 5. A remote platform in the Management Console</b>
		</p>
		<p>Note that containers of the remote platforms are not shown. This is because the information about 
		a remote platform are retrieved from the remote platform AMS in compliance with the FIPA specifications and
		Containers are a JADE abstraction, not a FIPA one. </p>
		
		<hr>
		<a href="index.html">Table of contents</a><br>
		<a href="jadeContainerTutorial.html">Previous</a><br>
	</body>

</html>